<?php
/**
 * View model controller.
 *
 * @author Martin "DevelX" Jurča
 * @version 2009-07-30
 */
interface View {
    /**
     * Notice message, e.g. Article saved.
     *
     */
    const MSG_NOTICE = 0;

    /**
     * Warning message, e.g. Can't contact remote server.
     *
     */
    const MSG_WARNING = 1;

    /**
     * Error message, e.g.: You don't have permission to access this data.
     *
     */
    const MSG_ERROR = 2;

    /**
     * Add new items and keep allready contained.
     *
     */
    const MENU_ADD = 0;

    /**
     * Add new items and update allready contained.
     *
     */
    const MENU_UPDATE = 1;

    /**
     * Replace all menu items with new.
     *
     */
    const MENU_REPLACE = 2;

    /**
     * Adds CSS file to display.
     *
     * @param String $url URL to the file.
     */
    public function addCSS($url);

    /**
     * Adds JS file to use.
     *
     * @param String $url URL to the file.
     */
    public function addJS($url);

    /**
     * Adds message of certain importance to display.
     *
     * @param String $message Message to display.
     * @param int $level Level of message importance.
     */
    public function addMessage($message, $level);

    /**
     * Displays template for module. These templates may be overridden by
     * current theme templates. It is also recommended to create modules using
     * theme templates.
     *
     * @param String $module Modules name.
     * @param String $name Template name.
     * @param Array $params Template parameters.
     * @param boolean $convert When set to true, the method will automatically
     *        convert all parameters to output character encoding. Set to false
     *        only and only if the parameters has been already converted.
     */
    public function displayTemplate($module, $name, &$params = array(),
            $convert = true);

    /**
     * Returns all messages of specified level of importance.
     *
     * @param int $level Level of messages importance.
     * @return Array List of messages.
     */
    public function &getMessages($level);

    /**
     * Returns list of all available themes.
     *
     * @return Array List of themes names.
     */
    public function &getThemes();

    /**
     * Returns name of currently used theme.
     *
     * @return String Name of current theme.
     */
    public function getCurrentTheme();

    /**
     * Returns step in navigation in form of array, beggining with web
     * navigation root and ending with curret page. Each item of list is
     * array ['url' => url, 'label' => label, 'title' => title]. This trace
     * is generated from stored website map.
     *
     * @return Array List of navigation steps. If trace is not available,
     *         returns false.
     */
    public function &getNavigationTrace();

    /**
     * Returns generated site map in the same format as menu, but menu items
     * contains key 'page' for menu on the corresponding page.
     *
     * @param String $rootPageUrl Page URL as root of site map tree to be
     *        returned.
     * @return Array Site map.
     */
    public function &getSiteMap($rootPageUrl);

    /**
     * Returns menu for current web page for requested area. The menu is
     * returned as array of menu items for smarty menu or mainmenu template.
     * If some item's url mathes page URL, this item has property active set to
     * true, otherwise the value is false. If menu is not defined for current
     * page, the method returns menu defined for page closer to website
     * navigation root recursively.
     *
     * @param String $area Area of menu position.
     * @return Array Requested menu as array of links information in form
     *         ['url' => url, 'href' => url, 'label' => label, 'title' =>
     *         title]. If menu is not available, returns false.
     */
    public function &getMenu($area);

    /**
     * Sets menu for current web page for current area. This way may be updated
     * website map but cannot be defined static menus.
     *
     * @param String $area Area of menu position
     * @param Array $items Items of menu. For details see the getMenu method.
     * @param int $how Method of adding menu to site map. Options are MENU_ADD,
     *        MENU_UPDATE, MENU_REPLACE
     */
    public function setMenu($area, &$items, $how);

    /**
     * Returns localized label template from database of global labels.
     *
     * @param String $key ID of label.
     * @param boolean $convert When set to true, the label is automatically
     *        converted to the output encoding.
     * @return String Localized label.
     */
    public function getLang($key, $convert = false);

    /**
     * When universal URL parsing rules are used, URL part without metadata
     * like "admin" or "ajax" is stored in array $_GET by key "url". This key
     * is automatically parsed by View module to parts by splitting the "url"
     * value by dashes ("/"). These parts may be than retrieved as array using
     * this method.
     * There are three ways of filtering the returned array using the $howMuch
     * argument: Use int to return the last $howMuch items or string value to
     * return all values from the first that matches this string including. The
     * last option is to use null and the method should return only parts for
     * which there is no set display configuration.
     *
     * @param String $howMuch The result array filtering argument.
     * @return Array URL parts without system metadata.
     */
    public function getUrl($howMuch);
}
?>
